Read Endpoints
All paths are relative to https://api.clocktower.finance.
All read endpoints use GET unless noted.
Protocol reads accept optional ?chainId= (decimal or CAIP-2). Omitted uses the REST default (Base 8453). See Chain selection.
Protocol and catalog
| Endpoint | Description |
|---|---|
GET /catalog | Machine-readable route catalog, tier limits, and chains[] registry (not filtered by chainId) |
GET /protocol/state | Current protocol fee configuration (?chainId= optional) |
GET /status | Lightweight health check |
Subscriptions
| Endpoint | Description |
|---|---|
GET /subscriptions | Search/discover subscriptions. Query: provider, token, frequency, cancelled (default false), includeDetails, first (lane cap: free 10, developer 25), skip, plus optional chainId. See Rate limits |
GET /subscriptions/due | Subscriptions due on a given day/frequency |
GET /subscriptions/:id | Single subscription by ID |
GET /subscriptions/:id/subscribers | Subscribers for a subscription |
GET /subscriptions/:id/fee-balance?address=0x… | Fee balance for a subscriber |
GET /subscriptions/:id/details | Current url/description (latest DetailsLog) |
Accounts
| Endpoint | Description |
|---|---|
GET /accounts/:address/subscriptions | Subscriptions for an account. Query: bySubscriber=true|false (default false = created as provider; true = subscribed to) |
GET /accounts/:address | Enriched account: subscribedTo and created arrays |
Tokens
| Endpoint | Description |
|---|---|
GET /approved-tokens | List approved tokens with minimum and paused |
GET /approved-tokens/:token | Single token configuration |
History and profiles (subgraph-backed)
These hit the expensive rate bucket and subgraph daily cap. Support ?first=N&skip=M pagination.
| Endpoint | Description |
|---|---|
GET /subscriptions/:id/history | Activity history (SubLog events) |
GET /accounts/:address/activity | Combined subscriber + provider activity |
GET /providers/:address | Latest provider profile |
GET /subscriptions/:id/details-history | URL/description change history |
Subgraph errors return a graceful response with an error field rather than failing the entire request.
History response fields
SubLog events include:
eventName— human-readable event typeamount,amountRaw,tokenDecimals— normalized amountsformattedTimestamp,formattedAmount
Design note
There is no raw GraphQL proxy. All subgraph access goes through shaped, rate-limited endpoints with formatting and normalization.